// Copyright 2025 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Package memory defines the entities to interact with agent memory (long-term knowledge).
package memory

import (
	"context"
	"time"

	"google.golang.org/genai"

	"google.golang.org/adk/session"
)

// Service is a definition of the memory service.
//
// The service ingests sessions into memory so that it can be used for
// user queries across user-scoped sessions.
type Service interface {
	// AddSession adds a session to the memory service.
	//
	// A session can be added multiple times during its lifetime.
	AddSession(ctx context.Context, s session.Session) error
	// Search returns memory entries relevant to the given query.
	// Empty slice is returned if there are no matches.
	Search(ctx context.Context, req *SearchRequest) (*SearchResponse, error)
}

// SearchRequest represents a request for memory search.
type SearchRequest struct {
	Query   string
	UserID  string
	AppName string
}

// SearchResponse represents the response from a memory search.
type SearchResponse struct {
	Memories []Entry
}

// Entry represents a single memory entry.
type Entry struct {
	// Content contains the main content of the memory.
	Content *genai.Content
	// Author of the memory.
	Author string
	// Timestamp shows when the original content of this memory happened.
	// This string will be forwarded to LLM. Preferred format is ISO 8601 format.
	Timestamp time.Time
}
